DISK OR NETWORK FILES To open a disk or network file the format of the FX: statement is as follows: FX:pathname Where the word pathname represents the name of the disk file or network node you wish to connect to. The pathname is formed per DOS file name conventions for specifying drive, directory, root file name, and file suffix. If the file exists, then it is made available for the PILOT program to read from or write to. If the named file does not exist, then the FX: statement automatically creates a file with that name, containing zero bytes of data. The file is made available to read from or write to. The FIZ function may be used to determine whether a file exists prior to attempting to open it. A disk file can be thought of as a list of bytes numbered from 0, for the first byte, up to the size of the file. To read data from the file use the FI: statement as shown above. The position-expression is evaluated to a number. The number represents an offset from the beginning of the file where reading is to begin. The byte at the specified location in the file is the first byte read into the string variable. The number of bytes copied into the string variable is equal to the maximum length established for the string variable when it was created. If the FI: statement attempts to read beyond the length of the disk file, then the string variable is padded out with CHR(255) characters to its maximum length. EXAMPLE 1: Open a disk file named DATA, read 20 bytes from the file, starting at byte position 15. D: B$(20) FX: DATA FI:15,B$ The FO:, or FILE OUT statement can be used to write data into a disk file. The position-expression determines the byte offset in the file where data is first written. The number of bytes written to the file is equal to the length of the data expression on the FO: statement. In using disk files you can think of the disk file as a long string of bytes. Each byte is addressable by its byte offset from the file start. However, it is often convenient to think of the file as a series of records, each record being a pre-determined number of bytes in length. For example, assume that your goal is to keep a file of student names and scores. You may decide that the file will consist of a series of 50-byte records. Each one would hold the name and score for one student. Also assume that in the first record of the file is the number of the next available record in the file. The following program examples show how to set this file up initially and how to write a record into the file. This example illustrates the use of the file statements. In practice, you would use KEEP to simplify the task. EXAMPLE 2: create file to save student scores FX:RECORDS (create file named RECORDS) FO:0," 1" (write 1 into the first record) EXAMPLE 3: save a student name and score in the RECORDS file R: set up strings D:NAME$(30),REC$(50),X$(3) . . . program runs here, assume that student . . . name is stored in NAME$, and score is . . . in the numeric variable SCORE R: construct student record with trailing R: CR and LF characters C:REC$(49,2) = CHR(13) !! CHR(10) C:REC(1,30) = NAME$ C:REC(31,18) = SCORE R:determine next available record FX:RECORDS FI:0,X$ FO:X$,REC$ R:update record number at the start of file C: X$(1,3) = X$ + 1 FO:0,X$ FX: PRINTER OR AUXILIARY PORT FILES The system printer device, or the auxiliary RS-232 serial interface can be accessed as a PILOT file. These special files can be used for output only. To open the printer as a file use: FX:PRN: To open the serial interface as a file use: FX:AUX: The serial interface can be used as a simple control mechanism for video disc or other external devices which have an RS-232 interface. One consideration for such devices is that both the computer and the other device must be set up to communicate at the same baud rate (speed). The baud rate on the computer end is set up prior to starting your PILOT program by issuing the DOS MODE command. This command could be placed in your AUTOEXEC.BAT file so that it happens each time the computer is turned on. A sample MODE command to set the baud rate to 1200 baud might look like this: MODE COM1:1200,N,8,1 See the DOS manual for further information on the MODE command. Once open, the FO: statement may be used to write data to the printer or to the device attached to the serial interface. The format of the FO: statement is: FO:0,expression The "0" is ignored for these devices. The string value of the expression is written to the device. No extra control characters are automatically written after the expression value. If you wish to transmit a RETURN or LINE FEED after the data, you must append these characters to the data. EXAMPLE 4: Write a line to the printer, then space the printer up one line. FX:PRN: FO:0,"Hello world." !! CHR(13) !! CHR(10) EXAMPLE 5: Control Video Disc Player From PILOT. This example assumes that a Pioneer LDV-700 and Pioneer IU-04 interface is attached to the serial interface and that the baud rate has been set via a MODE command prior to running the PILOT program. FX:AUX: R: next play frame 1000 as still frame FO:0,"F1000SI" !! CHR(13) R: next line plays 5 sec from frame 2345 FO:0,"F2345SP@5" !! CHR(13) R: next line turns off video disc FO:0,"Q" !! CHR(13) The actual command strings written to the video disc player by the above FO: statements may change for another brand or model of disc player. But the method used in PILOT to control the device is the same for any device which has a serial, RS-232 interface. HEAP FILE The heap facility permits the PILOT program to make use of very large computer memory as a temporary, very fast file. The program creates a heap out of otherwise unused RAM. Once the heap is created the program can write string data to the heap, and read it back later in the program. In effect the heap becomes an unlimited extension to the program string space. When the program ends and returns to DOS the contents of the heap are discarded. To establish the heap execute the following statement once at the beginning of the program use: FXH: n where n is a number indicating the size, in bytes, to be set aside for the heap. An XSPACE error occurs if the amount is to great for the system in use. To estimate the maximum size of the heap for a particular system proceed as follows. From DOS before running PILOT run CHKDSK to get the amount of unused memory. From that subtract 182K for PILOT. The remainder is available. If the program is to call other programs or languages (via EXEC) you must leave sufficient unused space for those programs. Only the first successful FXH: statement has an effect. Once the heap is set up, other FXH: statements are ignored. The heap does not count as the one allowed open file. So even though the heap is in use one additional disk file may be open. To write data to the heap use the following: FOH: n,string-value where n is the byte position within the heap at which the string-value is to be written. The first byte position in the heap is location 0. The string value may be a string variable name or any string expression. To retrieve the data into a string variable again use the statement: FIH: n,V$ where n is the position in the heap from which the data is to be read, and V$ is any string variable name. The statements FOH: and FIH: work exactly like FO: and FI: for disk files. The difference is that writing and reading the heap is very fast, taking no more time than a simple assignment statement. The heap can serve as a quick access storage bin for sprite tables, graphic images, machine language subroutines, etc. Items to be loaded from disk files into the heap must be moved there through string variables by reading from disk to the string via FI:, then writing to the heap from the string via FOH:. EXAMPLE 6: Create a heap and move two graphic images to the heap. FXH: 30000 DX:P$(10000) FX:PIC1.SQZ FI:0,P$ FOH:0,P$ FX:PIC2.SQZ FI:0,P$ FOH:10000,P$ EXAMPLE 7: display a graphic image from the heap FIH:10000,P$ V:P$ See also: AUX(0) function, FIZ function, MODE (DOS manual) GRAPHICS - display graphic images G: turtle-graphics-command-list GX: graphics-image-filename GSX: graphics-image-filename The GRAPHICS statement is used to control the graphics screen display. There are several types of graphics which can be used: TURTLE GRAPHICS: to draw colored points, lines, and shapes either by absolute pixel coordinates or by directing an invisible "turtle" to walk in various directions while drawing a line wherever it has gone. Turtle graphics in PILOT is similar to what is found in the LOGO language. IMAGE GRAPHICS: a graphics image is a stored picture or full screen graphic that has been created outside of the PILOT program and stored in a disk file. The GX: statement can display such a picture by painting the entire image on the screen in one operation. SCREEN SAVE/RESTORE: To facilitate the creation of dialog boxes, pull-down menus, and other types of screen overlays, the GSX: and GX: statement provide a way to take a snapshot of the screen, save it in internal memory, then instantly put the screen back as it was on command. SPRITE GRAPHICS: a sprite is a smaller picture which can be placed anywhere on the screen or can be moved around (animated) on the screen by attaching it to the turtle, and allowing the turtle to "drag" it around on the screen. TURTLE GRAPHICS The turtle graphics commands are valid only for graphic screen modes, namely modes 4, 5, 6, 13, 14 and 16. The G: statement is used for turtle graphics. After the colon you can write a list of turtle graphics commands. The list can contain one or more of the following commands, separated by ";" characters. To draw lines you tell the (invisible) turtle which direction to head and how far to walk. As the turtle walks it can leave a colored line on the screen. The turtle's heading ranges from 0 degrees (straight up) to 359 degrees with the heading angle increasing as it rotates to the right. If the turtle walks off the screen it comes back on the opposite edge. In the command descriptions below n represents a numeric variable, an integer constant, or an expression enclosed in parentheses. Ar,d - arc or circle Draw an arc with radius of r turtle steps, starting at the angle equal to the turtle heading, and sweeping through an angle of d degrees. The turtle heading rotates right by d degrees, the turtle location remains unchanged. If d=360 a circle is drawn Bx,y - solid color bar Draws a bar, or solid box, with the upper left corner at the turtle location, x and y are the number of pixels across and down of the bar. The turtle is moved to one pixel down and to the right of the bar. Pn - paint an area Paints an area to color number n. The painted area starts at the turtle location and includes all adjacent pixels with the same color as the starting pixel. It is a flood fill which recursively wraps around all corners and shapes as necessary. Hn - set turtle heading to n degrees Rn - rotate turtle heading right n degrees Ln - rotate turtle heading left n degrees Fn - walk forward n steps Gx,y - set turtle location to pixel x,y Dx,y - draw a line to pixel location x,y Cn - set line color for F or D to n (0-3) Cn,w - set line color and line width The width can be set to 0 (no line), 1, 2 or 3. The default is a 1 pixel wide line. The line width affects draw, forward, and arc commands. E - erase screen to background color *n(...) - repeat the enclosed commands n times Wn - wait, or delay n 60ths of a second Xn - set horizontal scale factor Yn - set vertical scale factor S var$ - make string variable var$ the current sprite table Sn - sprite select Display, or erase sprite n, and attach sprite n to the turtle. S0 - detach sprite from the turtle Jn - jump back to a previous sprite Move turtle to location of sprite n and attach sprite n to the turtle. MODES AND COLORS Turtle graphics can be performed in modes 4,5,6,13,14 and 16. In modes 4 and 5 the screen is 320 pixels across by 200 down with valid line colors 0-3. Color 0 selects the current background color as set by TYPE SCREEN. Colors 1, 2 and 3 are determined by the current mode. See the TYPE SCREEN statement for more information on modes and colors. MODES 4 and 5: 320 x-pixels, 200 y-pixels, colors 0-3 MODE 4 COLORS: 1-green, 2-red, 3-yellow MODE 5 COLORS: 1-cyan, 2-magenta, 3-white Background color for modes 4 and 5 is color number 0. It can be selected from colors 0-15, with two possible intensities as documented under TYPE SCREEN. In mode 6 the screen is 640 pixels across by 200 down with one valid line color as set by the TS:Xn command. MODE 6: 640 x-pixels, 200 y-pixels, colors 0-1 With an EGA (Extended Graphics Adapter) the additional graphics modes are: MODE 13: 320 x-pixels, 200 y-pixels, colors 0-15 MODE 14: 640 x-pixels, 200 y-pixels, colors 0-15 MODE 16: 640 x-pixels, 350 y-pixels, colors 0-15 SCALE FACTORS The X and Y scale factors can be adjusted for a particular display to achieve uniformity in horizontal and vertical step sizes. The default value is X1;Y1 , which makes a turtle step size equal to one quarter of a pixel. To make a step equal to a pixel set the values to X4;Y4. Scale factors can also be used to change the aspect ratio between x and y directions as shown in the ellipse example below. EXAMPLE 1: Turtle graphics examples. G: *18(F60;R20) draws a circle G: *4(F80;L90) draws a box G: C2;*5(F160;R144) draws a red star G: X6;Y3;*36(F10;R10) draws an ellipse G: G10,20;D15,85 line (10,20)-(15,85) G: G(X+30),40;F(60*D) expressions as arguments G: A50,360;P2 a circle, filled in G: B20,20;B40,40 two bars G: C1,3;A50,180 a wide-line semi-circle IMAGE GRAPHICS A graphics image can be created by the GIE program or by other graphics creation products which can produce a 16K bit-mapped screen image, often called BSAVE/BLOAD format. Many useful graphics creation products do not use the BSAVE/BLOAD format to store pictures on disk. However, in these cases there is often a conversion process that can be used to convert the picture files to BSAVE/BLOAD format. The BSAVER utility may be useful doing this type of conversion. See also: Appendix C. To load a graphics image from a disk file and display it on the screen, first insure that the screen is in a graphics mode (4,5 or 6) and set the desired background color (if not already set). The following statement shows how to do these two things: TS:M4;B2 Then execute the following command: GX:filename PILOT can also save the current screen display in a disk file by the following command: GSX:filename The GX: and GSX: statements may also be used in text modes (0 though 3). The screen image file produced is 2K for 40 column screens or 4K for 80 column screens. Prior to executing a GX: statement to display a text screen, the screen mode must be set to the same mode in which the screen image was saved via a previous GSX: statement. The PIQ utility program may also be of interest when using image graphics. It can be used to compress a graphics image from BSAVE/BLOAD format into a compact format which takes up less disk space and displays more quickly. PIQ also provides for various screen wipes and special effects for partial or complete screen images. See also: Appendix C. SCREEN SAVE/RESTORE The GSX: statement can be used to make a copy of the current screen in ram memory. The command format is: GSX: (no arguments follow the colon) This command happens instantaneously, so it is useful for saving the screen display when the program is to be interrupted for a menu, dialog box, or other student-invoked control function. Once the screen has been saved, the program can modify the screen as necessary to converse with the student. This might involve the display of a menu box, help screen, note pad, calculator, or glossary. When the auxiliary function is complete, the screen can be restored to its original state by the command: GX: (no arguments follow the colon) The screen restore is instantaneous. Not only is the visual data put back as it was, but the cursor location, colors, and current and previous viewport data is put back as well. It is, however, up to the program to insure that prior to execution of the GX: statement, the screen mode is set to the screen mode that existed at the time of the GSX: statement. If the mode has not changed in the interim, then it need not be changed back again. But if the screen mode did change after the GSX: statement, then it must be changed back by the TS:Mn command just prior to the GX: statement. The MOD built-in function may be useful in determining the screen mode prior to the GSX: statement if it is not already known. Unlike other uses of the Graphics statement, the uses of GSX: and GX: are valid in any screen mode from 0 to 6. EXAMPLE 2: SYSX routine using GSX: and GX: R: come here when user pushes ESC key *SYSX GSX: TS:V10,30,5,11 TX:******************* : : M - Main menu : C - Calc : G - Glossary : :******************* AS: M:M!m JY:MENU M:C!c JY:CALC M:G!g JY:GLOSS *SYSX2 GX: E: *CALC TX:Input expression :such as 123.5 * 7 :or ENTER to return A: J(%B=" "):SYSX2 X:"C:Z=" !! %B T:#Z W:30 J:CALC *GLOSS TX:Glossary... ... W:100 J:SYSX2 SPRITE GRAPHICS A sprite is a picture, similar to a graphics image, except that a sprite is smaller. A graphics image is 320 pixels across by 200 pixels up and down (the entire screen). A sprite can range from 32 pixels by 32 pixels, to 64 pixels by 128 pixels. Sprites can be displayed in graphics modes 4, 5 and 6 only. A sprite can be used as a way to draw diagrams or pictures on the screen. One of the unique features of a sprite is that it can be animated or moved on the screen. This is accomplished by use of the turtle graphics commands of the G: statement. To move a sprite you need only "attach" the sprite to the turtle, then move the turtle via forward or draw commands. As the turtle moves, rather than drawing a line as it usually would, it moves the sprite along with it on the screen. To take it a step further, you can move several sprites apparently at the same time by telling the turtle to take turns jumping from one sprite to the next, moving each a little bit on each turn. The use of sprites is discussed in great detail in the section of this document entitled "Sprites". JUMP - goto a destination J: label J: #variable J: @A J: @P J: @-P J: @M Unless otherwise instructed, PILOT executes each statement in your program one after the other, in the exact order that the statements are written. With the JUMP statement you can alter this order by branching to a specified location. The location can be a statement label, a numeric variable, or one of four possible special destinations which are commonly needed. JUMP TO A LABEL The first form of the JUMP statement above transfers control to the statement following the specified label. Although the statement label in the program is preceded by an "*", you do not put the "*" character on the JUMP statement. EXAMPLE 1: jump to a label J:PART4 . . . *PART4 T:This is chapter 4. If the label name to which the program should jump is contained in a string variable, use the Execute Indirect statement to perform the jump as shown in this example. EXAMPLE 2: jump to a string variable, say X$: X:"J:" !! X$ or if the jump is to be conditional: X(condition):"J:" !! X$ JUMP TO A NUMERIC VARIABLE The second format shown above permits a jump to a location stored in a numeric variable. This is a special purpose use which can be used in only one way. The numeric variable used in the Jump can be set by the statement: C: X = %E which sets variable X to the jump location of the return point from the most recent Use statement. Then to jump to this location use: J: #X This special case Jump is used only in the construction of an Escape routine which links to another module then expects to return to the point from which the escape routine was called. JUMP TO LAST ACCEPT STATEMENT The third form of the JUMP shown above is used to branch back to the last ACCEPT statement that was executed. This is useful to allow the student to re-answer the question just answered. EXAMPLE 3: jump to last ACCEPT T:What is 2+3? A: M:5 TY:Right TN:No, try again JN:@A JUMP TO THE NEXT MATCH When a student response is evaluated, there is sometimes a series of MATCH commands to test for various correct and incorrect possibilities. After each MATCH might be a series of statements to be executed if the MATCH is YES. Otherwise it is convenient to jump directly to the next MATCH to check for the next possibility. EXAMPLE 4: jump to next MATCH M:calcium JN:@M . . . M:silicon JN:@M . . . M: . . . JUMP TO NEXT PROBLEM If a program consists of a set of questions or problems, presented one after the other, it can be convenient to start each question section with the P: statement. Then, from anywhere within the previous question, the program can branch to the next problem without having to place a label on each question. EXAMPLE 5: jump to next problem M:Italy TY:Right, let's go on. JY:@P . . . P: T:Question 14. T:... JUMP TO LAST PROBLEM The final format of the Jump permits the program to jump back to the last Problem statement passed. This could be useful in going back to the start of the current section or when going back to accept another answer when the cursor must be positioned prior to letting the student answer again. EXAMPLE 6: jump to last Problem P: TS:G10,5;F4;B1 A: . . . J:@-P See also: STATEMENT LABELS KEEP RECORDS - save data on disk K: expression The KEEP statement provides a simple way to write data to a disk file for later manipulation. It can be used to store student progress records, scores, remarks from the student to the author, student answers, etc. The file written by the KEEP statement is a text file which can be displayed by the DOS TYPE command or examined by a text editor, such as EZ. It can also be read by another program to perform statistics or other reporting. The default file name used to store data written by the KEEP statement is K.REC, but the K option of the PROBLEM statement can be used to specify any filename, pathname, or network file name to be used instead. You need not take any action to create the keep file prior to running the PILOT program. If it does not exist, the KEEP statement automatically creates the file. Each time the KEEP statement is executed, the string value of the expression after the colon is written to the current keep file. A new-line sequence is appended to the string expression as it is written to the file. This means that each KEEP adds one text line to the keep file. The keep file continues to grow until it is explicitly erased by a DOS command. EXAMPLE 1: save student name and score T:Well, $NAME$ , you got #SCORE right. K: NAME$ !! SCORE E: See also: PROBLEM LINK - chain to another program file L: filename L: filename, destination Most programs you write should be divided into separate files, or modules. This facilitates program editing and helps keep an organized structure to your program. The LINK statement is used to transfer control from one program module to another. LINK is similar in use to the CHAIN statement of BASIC. When LINK is executed, the current program is removed from memory and the linked program is loaded into memory. All variables are retained from one module to the next. If you wish to Link to a string variable, see example 3 below. EXAMPLE 1: link to another program file L:CHAPTER7 In the above, the program is assumed to be in file CHAPTER7.PIL. With LINK you can start the new module at the beginning or at any label within the module. EXAMPLE 2: link to a label in another file L:CHEMX,Q3 The above links to file CHEMX.PIL, then does an automatic JUMP to label Q3 in that file. EXAMPLE 3: link to file name in a string variable, say X$ X:"L:" !! X$ See also: JUMP MATCH - compare student response M:pattern MS:pattern MJ:pattern MX:expression MATCH is used to test the answer given by the student to a previous ACCEPT statement. There are two types of MATCH, pattern matching and numerical matching. In either case, the result of the MATCH is a YES or a NO. The YES or NO can subsequently be tested by use of the Y or N conditionals. PILOT does not make any assumptions about the correctness or incorrectness of an answer. You can use MATCH equally well to test for correct answers or anticipated incorrect answers. YES does not necessarily always mean correct and NO does not necessarily always mean incorrect. PATTERN MATCHING MATCH compares the student answer buffer (%B) with the pattern after the colon on the MATCH statement. The result is a YES or NO match which can be tested by the Y or N conditionals. When comparing, if the student answer contains the match pattern anywhere within the student answer, it is considered a YES match. EXAMPLE 1: simple MATCH M:HAT student answer: CHATTER gives YES student answer: HAT gives YES student answer: CAT gives NO SPECIAL MATCH CHARACTERS When writing the pattern, you can use the following special characters within the pattern. * matches any one character & matches any string of zero or more characters It can be considered to separate several items which must occur in specific order but that may have other data between items. @ separate items which must be present but may be in any order ! separate alternative patterns % matches only a space or the start or end of the answer NEGATION If the first character of the match pattern is the not character, "^" , then the sense of the match is inverted. That is, it will yield a YES if the match pattern is NOT found in the student answer, and will yield a NO if the match pattern IS found in the student answer. SPELLING ERRORS The S modifier can be appended to the MATCH op code. MS: is sometimes called MATCH SPELLING. The Spelling modifier makes the MATCH more liberal in its comparison. If the student answer is off by only a minor spelling error, then the MATCH is still YES. A minor spelling error is one wrong letter or two inverted letters. EXAMPLE 2: Various MATCH statements. M:HAT HAT - YES CHATTER - YES M:%HAT% HAT - YES CHATTER - NO M:CAT&DOG CATDOG - YES CATS AND DOGS - YES DOGS AND CATS - NO M:CAT@DOG CATDOG - YES CATS AND DOGS - YES DOGS AND CATS - YES MS:GREEN GREAN - YES GRENE - YES MS:CAT!DOG CAT - YES COT - YES DIG - YES M:H*T HOT - YES HAT - YES HT - NO M:^DOG DOG - NO CAT - YES M:RED&BLUE!HOT RED, WHITE, BLUE - YES HOT - YES RED - NO SYSTEM VARIABLES AFTER A MATCH There are three system variables set after a pattern match. Each is set to zero if the pattern did not match, otherwise each is set as follows: %N - alternate answer indicator %N is the number of the alternate answer which matched when an "!" is used to separate possible alternate answers. For example, M:CAT!DOG!HORSE if the student types CAT, %N=1, if the student types DOG, %N=2, etc. %M - offset of match in student answer %M is the byte location within the student answer (ie. subscript within %B) at which the match began. %L - match length %L is the number of bytes within the student answer (%B) which matched. Example: M:C&T If student reply is SCANTY, %M=2, %L=4 AUTOMATIC JUMP TO NEXT MATCH Appending the J modifier to the MATCH op code causes a JUMP to the next MATCH if this match results in a NO. NUMERIC MATCH The MX: statement is used to make numeric comparisons. The argument after the colon is an expression. The expression is evaluated, if the numeric value of the expression is true (non-zero), the result of the MATCH is YES. If the numeric value of the expression is false (0), then the result of the MATCH is NO. EXAMPLE 3: numeric matching MX: FLO(%B) > 50 TY:Too big, try again. MX: X > 98.3 & X < 98.9 TY:Close enough. See also: ACCEPT, JUMP, CONDITIONALS NEW CHARACTER - define char pattern N:c . . . / / / (64 . and / characters) PILOT uses Ascii character codes 32 through 256 for printable characters. The ASCII code table defines only the characters from 32 through 127. This leaves 128 characters, from 128 to 256, for other uses. These characters are used in the text modes (modes 0 through 3) for the extended text mode characters. These include various line drawing characters, mathematical symbols and foreign characters. In the graphics modes (modes 4 through 6) the 128 extra characters are set aside as user-definable special characters. This means that you can design your own characters for special type fonts, foreign languages, or other special symbols. The special characters should not be confused with character "fonts". Special characters defined by the N: statement are restricted to the standard 8 by 8 pixel character size. Character fonts, described under the NS: statement, can be used for smaller or larger character representations. The NEW CHARACTER command can be used to change the 8 by 8 dot pattern for any of the 128 changeable characters. Prior to execution of any N: statement the characters from 128 to 255 have unpredictable display patterns in the graphics modes. Once at least one N: statement has been executed, the characters from 128 to 255 that have not been explicitly changed will have the same display pattern as the corresponding character in the range 0 to 127. The N: statement has no effect on the characters displayed in text modes. In text modes, the characters displayed are always the default text mode extended character set, as shown in Appendix B. The letter c shown in the format of N: above stands for any character from 128 to 255. (The EZ editor provides a way to enter characters in that range into a program.) It is followed by 64 periods and slash characters. They depict the pattern of zero (.) and one (/) bits that will be used to display the character. The 64 bits may be given on 8 lines of 8 bits each, to give a visual picture of the character pattern. The 64 bits may also be given all on one line or any desired format that adds up to 64. Intervening spaces and new lines are ignored. CHARACTER EDITOR Although you could write an N: statement and manually determine the pattern of dots and slashes, you would normally use the Character Editor included in the EZ editor. It makes the process of creating character patterns very easy. EZ also allows you to see your re-defined characters while you are editing your program if you wish. See also: The EZ Editor NEW HEIGHT/WIDTH - set font size NH: h,w The NH: statement may be used to change the default font character cell size. The font character cell size is used to compute row/column coordinates for cursor addressing by the "TS:Gc,r" command when in font display mode. When a font is activated as the current font (see NS: statement) it has a default character cell height and width, in pixels. This default height and width are usually set to accommodate the largest character in the font. When the program executes a TYPE SCREEN with a GOTO command to set the cursor, the character cell height and width are used to compute the pixel location for the cursor. A typical use of NH: is to set both height and width to 1. Thus the command to set the cursor location has the effect of absolute pixel addressing. Thus a font character could be written at any pixel on the screen. EXAMPLE 1: change to pixel addressing NH: 1,1 See also: NEW FONT NEW FONT - set font mode NS: variable$ NS: variable$,c1,c2,c3 NS: The NS: statement may be used to set "font display mode". NS: may be executed only with the screen in display mode 4 or higher. The "variable$" must be a character string variable which contains the desired character font. In font display mode all characters typed by the program or entered on the keyboard are displayed in the type size and style of the active character font. Character fonts can be used to display text in characters that range in size up to 24 by 24 pixels, and accommodate an unlimited variety of type styles. The character font may be one supplied with PILOT or may be one created by using the Font Editor, described in a later section of this document. The NS: statement with no parameters after the colon may be used to turn off font display mode and return to normal text display mode. Font display mode is also turned off by the mode set command of the TYPE SCREEN statement. When font display mode is entered the font text cursor is placed in the home position and color and spacing options are set to the defaults contained in the font. FONT COLORS A character font can define each character in one, two or three colors. So an individual character can contain as many as three different colored pixels. This provides for great flexibility in font design for outlines, drop shadows, etc. The three colors are numbered 1,2 and 3. Some fonts are designed with one color only. In this case the one color is normally color 3. The NS: statement provides for a way to re-map the three colors to any other three colors. In modes 4 and 5 the three new colors can be from 0 to 3. But in EGA extended modes (13,14 and 16) the three new colors can be selected from 0 through 15. So at any one time a character can be displayed in up to three of the colors supported in the current screen mode. To re-map the colors use the second form of the NS: statement above. The values for c1,c2 and c3 are the new color numbers for the three colors. The foreground color command of the TYPE SCREEN statement and the #n command of the TYPE statement both provide a means of changing the text color. Both of these commands set the new value for color number 3 of the font. So for fonts which are defined in one color, the same commands used when not in font display mode are used to set the text color in font display mode as well. HOW TO READ A FONT To use a font the program must first set up a string variable long enough to contain the font, and must read the font file into the string variable. By convention, PILOT font files have a file name suffix of ".PIF". The following example shows how to read a font file into a string variable. EXAMPLE 1: read a font file D: F$(5000) FX: HELV9.PIF FI: 0,F$ FONT CURSOR ADDRESSING Characters are displayed in font mode with proportional spacing. This means that each character is only as wide as necessary. Also, a character can be displayed at any pixel boundary, not only at the pre-defined character cells of normal text. When in font display mode the text cursor is kept in terms of pixels, not character cells. The cursor is considered to be at the upper left pixel of the cell in which the next character would be displayed. The XCR and YCR functions return pixel values in this mode. Viewports can be used with font display mode, but the viewport boundaries are still expressed in the character boundaries used for non-font mode. The result is that viewports are always defined on 8 pixel boundaries though the characters in the viewport might be displayed at any pixel. Cursor addressing within a viewport is relative to the home pixel of the viewport (upper left pixel). Proportional spacing improves readability and permits more text per line but it somewhat complicates the issue of cursor row/column addressing. The GOTO command of the TS: statement may be used to move the cursor to any screen position by specifying a row and column coordinate. Since each character is different size, each font has a default character cell height and width defined. These values usually represent average character size for the font. These average sizes are used to position the font text cursor. The cursor is positioned at the pixel represented by the column and row values multiplied by the default character cell size. The NH: statement provides a means of altering the effect of cursor addressing. With NH: the program can change the values multiplied by the row and column numbers. The most typical case is to execute the statement NH:1,1 after executing the NS: statement. This sets cursor addressing to pixel coordinates giving the program the ability to address the font text cursor to an absolute pixel.